home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr25 / msgxp120.zip / MSGX.DOC < prev    next >
Text File  |  1993-03-16  |  23KB  |  529 lines
  1.      
  2.      
  3.      
  4.      
  5.      
  6.      
  7.      
  8.                                    MsgX
  9.      
  10.                         Message Extraction Utility
  11.                                         
  12.                              Version 1.20 BETA
  13.                                         
  14.                                         
  15.                                         
  16.                                         
  17.                                         
  18.                                         
  19.                                         
  20.                                         
  21.                                         
  22.                                         
  23.                                         
  24.                                         
  25.                                         
  26.                                 Dave Fisher
  27.                                         
  28.                         LiveNet, 1:170/110@fidonet
  29.      
  30.      
  31.      Description
  32.      
  33.      MsgX is a message extraction program that will select messages
  34.      from any *.MSG or Squish formatted area base and store them in a
  35.      text file or archive.  MsgX will allow you to specify date ranges
  36.      of messages to extract.  It is mainly intended to act as an
  37.      archival and storage method for echoes and can be run on a daily,
  38.      weekly, or monthly basis.  The collected messages can optionally
  39.      be compressed into an archive using your favorite archival
  40.      program.  If desired, MsgX will also add an entry in the
  41.      specified FILES.BBS for the newly created archive.
  42.      
  43.      MsgX can archive multiple areas to one archive in a single pass.
  44.      
  45.      If you are running MsgX under OS/2, you will need the file
  46.      MSGAPI.DLL in one of the directory paths specified using the
  47.      LIBPATH variable.
  48.      
  49.      If you are running MsgX under DOS, there are no special
  50.      instructions.
  51.      
  52.      Usage
  53.      
  54.      MsgX [@CtlFile] AreaTag(OutputFile) [, AreaTag(OutputFile), ...]
  55.           /[no]AppendMsgs                   default: NoAppendMsgs
  56.           /Archive = <path+file name>       default: "Constructed"
  57.           /[no]Compress                     default: NoCompress
  58.           /Config = <path+file name>        default: MsgX.Cfg
  59.           /[no]Control                      default: NoControl
  60.           /Dates = (from_date, to_date)     default: All dates
  61.           /Description = "<filesbbs desc>"  default: "Constructed"
  62.           /[no]Kill                         default: NoKill
  63.           /LimitSize = <number of messages> default: No Limit
  64.                OR
  65.           /LimitSize = (threshold, del cnt) default: No Limit
  66.           /[no]Log                          default: NoLog
  67.           /LogFile = <path+file name>       default: None
  68.           /LogLevel = <1..4>                default: 4
  69.           /Margin = <right margin>          default: 79
  70.           /[no]Quiet                        default: NoQuiet
  71.           /[no]Seenbys                      default: NoSeenBys
  72.           /Skip = <number of messages>      default: 0
  73.           /[no]Statistics                   default: Statistics
  74.           /Title = "<header title>"         default: "Constructed"
  75.           /[no]Update                       default: NoUpdate
  76.           /[no]Write                        default: Write
  77.      
  78.      Notes on the syntax:
  79.      
  80.           Qualifiers can appear in any order, and are only significant
  81.           to four characters.  Thus, /Statistics is the same as /Stat.
  82.           
  83.           If a qualifier follows a quote mark ("), please separate
  84.           with a space.  For example, the following line is incorrect:
  85.           
  86.           /description = "Men's Issue Forum"/noseenbys/update
  87.           
  88.           The following is correct:
  89.           
  90.           /description = "Men's Issue Forum" /noseenbys/update
  91.           
  92.           Normally, qualifiers can be next to each other, but due to
  93.           technicalities with the language used for MsgX and the
  94.           operating system, the above caveat applies.
  95.      
  96.      Disclaimer!
  97.      
  98.      This program is shareware.  There is absolutely no warranty for
  99.      this program or guarantee that it will work.  The user of the
  100.      program assumes all risk.  While I feel confident that this
  101.      program will not harm your system in any way, by using this
  102.      program, you agree to assume full responsibility for any adverse
  103.      effect to your system.
  104.      
  105.      Ok.  Now with that out of the way -- please send me mail and let
  106.      me know if you are using MsgX!  I'd like to get an idea of
  107.      whether this program has been useful for others, as it has been
  108.      for me.  Also, please send any comments, suggestions and/or
  109.      problem reports.  I can be reached at:
  110.      
  111.           Dave Fisher
  112.           LiveNet, 1:170/110@fidonet.org
  113.           
  114.           
  115.      
  116.      Parameters
  117.      
  118.      @CtlFile
  119.      ---------------------------------------------------------
  120.      
  121.      If a control file is specified, all command line parameters and
  122.      qualifiers will be read form that file instead of the command
  123.      line itself.  This is helpful is you have too many options or
  124.      areas specified, and they will not fit on the command line due to
  125.      the limitation imposed from the operating system.
  126.      
  127.      If @CtlFile is specified, do not specify any other parameters on
  128.      the command line.  For example:  "MsgX @c:\bbs\msgxos2" is valid
  129.      whereas "MsgX @c:\bbs\msgxos2 /Date=( previous week )" is not.
  130.      In this example, /Date should be written in msgxos2.ctl.
  131.      
  132.      If an extention is not specified, MsgX will default to the
  133.      extension to .CTL.  See file Example.Ctl for more information.
  134.      
  135.      
  136.      AreaTag(Output_File_Name)
  137.      ---------------------------------------------------------
  138.      
  139.      This parameter is the areatag name as specified in Maximus's
  140.      message control file (usually named MSGAREA.CTL).  You can
  141.      specify as many tag names as will fit on the command line.
  142.      Separate each tag name with a comma.  Note that local message
  143.      areas and the netmail area do not have "echotag" names.  In order
  144.      to extract messages from these areas, you will have to specify
  145.      the name of the area as defined by the "Area [name]" statement in
  146.      MSGAREA.CTL.  For echos, use the "MsgName [name]" names.
  147.      
  148.      AreaTag may include wildcard match characters '*' for multiple
  149.      character matches, and/or '?' for single character matches.
  150.      
  151.      An optional file name may also be specified within parenthesis.
  152.      This is the name of the text file that will be created.  This
  153.      text file includes a very short header and then all the collected
  154.      messages from the area.
  155.      
  156.      If the /Compress option is enabled, the files will be created
  157.      within the Work Directory.  They will be deleted after they are
  158.      successfully compressed.  Therefore, do not specify a path for
  159.      the text files if you are compressing them.  If you are not
  160.      compressing the files, then Output_File_Name can have a fully
  161.      qualified path.  If it does not, the file will be created in the
  162.      current directory.
  163.      
  164.      The output file name can include one or more of the following
  165.      date expansion macros:
  166.      
  167.          %a - The abbreviated weekday name
  168.          %A - The full weekday name
  169.          %b - The abbreviated month name
  170.          %B - The full month name
  171.          %d - Day-of-month as a decimal (01-31)
  172.          %j - Day-of-year as a decimal (001-365)
  173.          %J - Day-of-year as a year/julian decimal (n001-n365)
  174.               where 'n' is the last digit of the year
  175.          %m - Month as a decimal (01-12)
  176.          %w - Weekday as a decimal (1-7), Sunday being 1,
  177.                                           Saturday 7
  178.          %W - Weekday as a decimal (1-7), Monday being 1,
  179.                                           Sunday 7
  180.          %y - Year without century (00-99)
  181.          %Y - Year including century (1970-2069)
  182.      
  183.      All macros are expanded based on the TO date of the date range.
  184.      Please note that each macro is case sensitive.
  185.      
  186.      NOTE:  If no file name is given within, the default file name
  187.      will be the AreaTag name with the extension of .TXT.
  188.      
  189.      For example:
  190.      
  191.           MsgX OS2BBS, OS2, OS2LAN, OS2HW, OS2DOS
  192.                /Dates = ( previous week )
  193.                /Archive = c:\max\files\echos\OS%y%m%d
  194.                /Compress
  195.                /Update
  196.      
  197.      This will extract all messages from the indicated areas for the
  198.      previous week.  They will be stored in individual text files
  199.      named OS2BBS.TXT, OS2.TXT, etc. and compressed within one archive
  200.      named OS920321.ZIP (if the end of the week was March 20, 1992 and
  201.      the archive method was PKZIP).
  202.      
  203.      The example could have also been written like this:
  204.      
  205.           MsgX OS2BBS(OA%y%m%d), OS2(OB%y%m%d), OS2LAN(OC%y%m%d),
  206.                OS2HW(OD%y%m%d), OS2DOS(OE%y%m%d)
  207.                /Dates = ( previous week )
  208.                /Archive = c:\max\files\echos\OS%y%m%d
  209.                /Compress
  210.                /Update
  211.      
  212.      Where each individual text file is now named with the year,
  213.      month, and day as the archive.
  214.      
  215.      MsgX will automatically determine whether the area is Squish or
  216.      *.MSG format.
  217.      
  218.      
  219.      Qualifiers
  220.      
  221.      /[no]AppendMsgs
  222.      ---------------------------------------------------------
  223.      
  224.      The qualifier will first extract any text files from the
  225.      specified archive into the Work Directory.  Any extracted
  226.      messages will then be appended to these files (if the file names
  227.      match the files that were in the archive, of course).
  228.      
  229.      Appending messages is the default behavior of MsgX.  So if a file
  230.      was left in the Work Directory by mistake and that file matched
  231.      the name of the current extraction, there is a risk that messages
  232.      will be appended to that file.  Thus, it is a good idea to let
  233.      MsgX take full control of the Work Directory.
  234.      
  235.      /Archive
  236.      ---------------------------------------------------------
  237.      
  238.      If the /Compress qualifier is active, you can specify the name of
  239.      the archive.  (MsgX will ignore an extension if you put one on
  240.      it.)
  241.      
  242.      If you are only extracting ONE area and do not specify an archive
  243.      name with /Archive (or in the configuration file), MsgX will
  244.      create an archive with the same base name as the text file of
  245.      messages.
  246.      
  247.      If you are extracting MULTIPLE areas and do not specify an
  248.      archive name with /Archive (or in the configuration file), MsgX
  249.      will create the archive ECHOS.ZIP in the current directory.
  250.      
  251.      The archive name can be a fully qualified path and may include
  252.      any of the date expansion macros (%d, %m, etc.).
  253.      
  254.      /[no]Compress
  255.      ---------------------------------------------------------
  256.      
  257.      This qualifier allows you to compress the output file(s) into a
  258.      .ZIP archive.  If extracting only one area, the name of the
  259.      archive will be identical to the output file name, except the
  260.      extension will be changed to .ZIP.  If extracting multiple areas,
  261.      the name of the archive must be specified using /Archive.
  262.      
  263.      If the archive exists, new message text files will either be
  264.      added or updated in the archive.  If the archive does not exist,
  265.      then a new one will be created.
  266.      
  267.      After the archive is successfully created or updated, the
  268.      original uncompressed output text file(s) will be deleted.
  269.      
  270.      Config = <path+file name>
  271.      ---------------------------------------------------------
  272.      
  273.      This is the name of the configuration file.  The default is
  274.      MsgX.Cfg in the current directory.  You can also define the
  275.      environment variable MSGX_CONFIG=<path+file name> instead of
  276.      using this qualifier.
  277.      
  278.      /[no]Control
  279.      ---------------------------------------------------------
  280.      
  281.      This qualifier controls whether CONTROL information (such as
  282.      PATH, REALNAME, etc) should be included in the message.  The
  283.      default is /NoControl.
  284.      
  285.      /Dates=(from_date, to_date)
  286.      ---------------------------------------------------------
  287.      
  288.      This qualifier will designate which dated messages should be
  289.      selected from the area.  Messages will be selected based on the
  290.      date they were received into the BBS (not the date the message
  291.      was written).
  292.      
  293.      The 'from_date' and 'to_date' is formatted as dd-mmm-yyyy.  For
  294.      example, January 1, 1992 is represented as 1-Jan-1992, December
  295.      25, 1991 as 25-Dec-1991, etc.
  296.      
  297.      The following keywords can be used in place of 'from_date' and
  298.      'to_date':
  299.      
  300.          /date = ( current month )
  301.          /date = ( current week )
  302.          /date = ( current day )
  303.      
  304.          /date = ( previous month )
  305.          /date = ( previous week )
  306.          /date = ( previous day )
  307.      
  308.      The calculated 'current' or 'previous' date will be relative to
  309.      the current computer date/time.  These keywords can be very
  310.      helpful if you want to have the messages archived automatically
  311.      at the end of the week or month.
  312.      
  313.      /Description = "<filesbbs desc>"
  314.      ---------------------------------------------------------
  315.      
  316.      If you choose the /Update option, you can specify the description
  317.      line for the archive file.  This description line may include any
  318.      of the date expansion macros available (%m, %y, etc.).
  319.      
  320.      If the archive already existed, and message text files were
  321.      therefore added or updated, the FILESBBS will not be updated.
  322.      The file will only be updated when a new archive has been
  323.      created.
  324.      
  325.      /[no]Kill
  326.      ---------------------------------------------------------
  327.      
  328.      This will kill any messages that are successfully extracted.  If
  329.      /NoWrite is specifed, messages will still be deleted.  This gives
  330.      MsgX the ability to manage the size and/or content of a message
  331.      base.
  332.      
  333.      /LimitSize = <number of messages>
  334.      /LimitSize = ( threshold, delete_count )
  335.      ---------------------------------------------------------
  336.      
  337.      This qualifier has two possible meanings, depending upon the
  338.      number of parameters used.  In both cases, this qualifier will
  339.      override any date ranges specified.  If /Compress is specified,
  340.      messages will first be archived and then deleted.
  341.      
  342.      If you wish to save the first or so messages, be sure to specify
  343.      /Skip.
  344.      
  345.      The first form indicates the final size of the message base.
  346.      Thus, if there are 212 messages in the message base and
  347.      /LimitSize=200 is indicated, the first 12 messages will deleted
  348.      (unless /Skip is used, in which case the first 12 messages after
  349.      the specified number of messages are skipped).
  350.      
  351.      The second form indicates that a certain number of messages
  352.      (delete_count) should be deleted only if there are 'threshold'
  353.      number of messages already there.  For example, if there are 212
  354.      messages in the message base and /LimitSize=( 200, 50 ), then the
  355.      first 50 messages will be extracted from the message base,
  356.      resulting in a final message base size of 162.  If SMOG were run
  357.      again, then nothing would be extracted since 162 is less than 200
  358.      messages.  Once again, if /Skip is specified, then the specified
  359.      number of messages will first be skipped.
  360.      
  361.      /[no]Log
  362.      ---------------------------------------------------------
  363.      
  364.      This qualifier will turn the logging function on and off.
  365.      
  366.      /LogFile = <path+file name>
  367.      ---------------------------------------------------------
  368.      
  369.      This qualifier defines the name of the log file.
  370.      
  371.      /LogLevel = <1..4>
  372.      ---------------------------------------------------------
  373.      
  374.      This qualifier defines the level of message detail in the log
  375.      file.  Level 1 is the least detailed, while Level 4 is the most
  376.      verbose.  The levels indicate the 'importance' of a message,
  377.      where Level 1 is the most important (usually error messages).
  378.      
  379.      /Margin=<right margin>
  380.      ---------------------------------------------------------
  381.      
  382.      This qualifier will control the length of the line for each
  383.      message.  The default is 79, but can be changed to anything
  384.      between 1 and 132.
  385.      
  386.      /[no]Quiet
  387.      ---------------------------------------------------------
  388.      
  389.      This qualifier controls whether the program should emit an
  390.      printed output.  If /Quiet, the only output will be the program
  391.      copyright line and any error messages.  The default is /NoQuiet.
  392.      
  393.      /[no]Seenbys
  394.      ---------------------------------------------------------
  395.      
  396.      This qualifier controls whether the SEENBY's lines should be
  397.      included in the message extraction.  The default is /NoSeenBy.
  398.      
  399.      /Skip = <number of messages>
  400.      ---------------------------------------------------------
  401.      
  402.      This qualifier specifies the number of message to skip before
  403.      attempting an extraction and/or deletion.  If you are extracting
  404.      or deleting from a Squish message base, this qualifier is not
  405.      necessary since MsgX will set the number of messages to skip
  406.      based on the "-$s" command in Squish.Cfg.
  407.      
  408.      /[no]Statistics
  409.      ---------------------------------------------------------
  410.      
  411.      This qualifier will produce a day-by-day and summary statistical
  412.      analysis of the messages received.  Information includes average
  413.      messages per day, average bytes per day, largest message size,
  414.      etc.  The default is /Statistics.
  415.      
  416.      
  417.      /Title = "<header title>"
  418.      ---------------------------------------------------------
  419.      
  420.      This qualifier will override the default header title for the
  421.      message text file.  Normally, MsgX will center a title at the top
  422.      of the file of extracted messages.  This title is either derived
  423.      from the MsgInfo statement in the MsgArea.Ctl file, or
  424.      constructed from the area tag name (if the area definition was
  425.      read from Squish.Cfg or Areas.Bbs).  In the latter case, all
  426.      underscores will be replaced with spaces, and words will be
  427.      capitalized.
  428.      
  429.      This default construction can be overriden if /Title is
  430.      specified.  However, please note that if you have specified
  431.      multiple areas (or wildcards) that this title will be displayed
  432.      at the top of each file.  Thus, if you would like to customize
  433.      the title, you may want to only specify one area per run of MsgX.
  434.      
  435.      /[no]Update
  436.      ---------------------------------------------------------
  437.      
  438.      This qualifier tells MsgX to update the file indicated by
  439.      /FilesBBS.
  440.      
  441.      If you do not specify a description (using /Description), then
  442.      the line added to this file will be in the following format:
  443.      
  444.      If running MsgX for only ONE area:
  445.      
  446.           <Archive file name> <Title> - <Date Range>, where 'Title' is
  447.           the name of the area from you Maximus message area control
  448.           file (MsgInfo statement).
  449.      
  450.      If running MsgX for multiple areas:
  451.      
  452.           <Archive file name> <Title> - <Date Range>, where 'Title' is
  453.           a list of area tag names, separated by commas.
  454.           
  455.      If a the file specified by /FilesBBS does not exist, one will be
  456.      created.
  457.      
  458.      /[no]Write
  459.      ---------------------------------------------------------
  460.      
  461.      This qualifier will control whether the output text file will
  462.      created.  At first glance, this may seem like a silly qualifier
  463.      since this is the primary purpose of MsgX!  However, MsgX also
  464.      does a brief analysis of the entire area and will display some
  465.      statistical information about the area.  If you only want the
  466.      statistical information, you can specify /NoWrite, and an output
  467.      file will not be created.
  468.      
  469.      
  470.      Examples
  471.      
  472.      The following examples are broken apart on several lines for
  473.      display reasons.  They would be entered on one line when actually
  474.      executed.
  475.      
  476.      Msgx MENS_ISSUES(men%%y%%b.txt)
  477.           /Desc="Men's Issues Forum for the Month of %b, %y"
  478.           /Archive=c:\max\files\echos\men%%y%%b
  479.           /noseenbys/nocontrol
  480.           /dates=( current month )/compress/update
  481.      
  482.      The above command exists in a batch file.  Notice the double
  483.      percent signs (%%).  This is necessary since we are not
  484.      indicating a batch substitution, and want the batch file to
  485.      ignore the percent sign.  Only one percent sign will actually be
  486.      passed to MsgX.  If today's date is February 29, 1992, MsgX will
  487.      create the file Men92Feb.txt and archive this to the file
  488.      \max\files\echos\Men92Feb.Zip.
  489.      
  490.      MsgX os2 /dates=( previous week )
  491.      
  492.      If the current date is February 12, 1992, MsgX will create the
  493.      file Os2.txt in the current directory.  This is the week of Feb
  494.      2, 1992 to Feb 8, 1992.
  495.      
  496.      The following is a OS/2 .CMD file that runs MsgX:
  497.      
  498.      /*----------------------------------------------------------*
  499.       * WEEKLY.CMD                                               *
  500.       *                                                          *
  501.       * Rexx procedure to perform weekly maintenance activities  *
  502.       *----------------------------------------------------------*/
  503.      
  504.      "c:"
  505.      cd "\bbs\msgx"
  506.      
  507.      msgxp "mens_issues(MN%%y%%m%%d.txt)
  508.      /archive=c:\max\files\echos\MN%%y%%m%%d
  509.      /compress/update/quiet/dates=( previous week )"
  510.      
  511.      if ( rc > 0 ) then
  512.      do
  513.          echo "Echo not extracted.  MsgX error " rc
  514.          exit
  515.      end
  516.      
  517.      msgxp "os2, Os2bbs, os2prog, os2lan, os2hw, os2dos
  518.      /archive=c:\max\files\echos\OS%%y%%m%%d
  519.      /compress/update/quiet/dates=( previous week )"
  520.      
  521.      if ( rc > 0 ) then
  522.      do
  523.          echo "Echo not extracted.  MsgX error " rc
  524.          exit
  525.      end
  526.      
  527.      exit
  528.      
  529.